.\" $Id: PAPI_list_events.3,v 1.12.12.1 2006/10/25 10:44:46 mucci Exp $
.TH PAPI_list_events 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_list_events \- list the events in an event set
.SH SYNOPSIS
C Interface

.nf
.B #include """papi.h"""
.BI "int PAPI_list_events(int " EventSet ", int *" Events ", int *" number ");"
.fi

Fortran Interface

.nf
.B #include """fpapi.h"""
.BI PAPIF_list_events(C_INT\  EventSet,\  C_INT(*)\  Events,\  C_INT\  number,\  C_INT\  check )
.fi

.SH DESCRIPTION
.LP
.B PAPI_list_events(\|)
decomposes an event set into the hardware events it contains.
.LP
This call assumes an initialized PAPI library and a successfully
added event set.

.SH ARGUMENTS
.I EventSet 
-- An integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3).
.LP
.I *Events 
-- An array of codes for events, such as PAPI_INT_INS. No more than 
.I *number
codes will be stored into the array.
.LP
.I *number 
-- On input the variable determines the size of the 
.I Events
array. On output the variable contains the number of counters in the
event set.
.LP
Note that if the given array
.I Events
is too short to hold all the counters in the event set the
.I *number
variable will be greater than the actually stored number of counter codes.

.SH RETURN VALUES
.TP
.B "PAPI_OK"
The call returned successfully.
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.

.SH EXAMPLES
.nf
.if t .ft CW
  /* Convert an event name to an event code */
  if (PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode) != PAPI_OK)
    exit(1);

  /* Add Total Instructions Executed to our EventSet */
  if (PAPI_add_event(EventSet, EventCode) != PAPI_OK)
    exit(1);

  /* Convert a second event name to an event code */
  if (PAPI_event_name_to_code("PAPI_L1_LDM",&EventCode) != PAPI_OK)
    exit(1);

  /* Add L1 Load Misses to our EventSet */
  if (PAPI_add_event(EventSet, EventCode) != PAPI_OK)
    exit(1);

  /* List the events in our EventSet */
  number = 4;
  if(PAPI_list_events(EventSet, Events, &number);
    exit(1);

  if(number != 2)
    exit(1);
.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_event_name_to_code "(3), " PAPI_add_event "(3), " PAPI_create_eventset "(3),"
.BR PAPI_event_code_to_name "(3), " PAPI "(3), "
